home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / getspent.z / getspent
Encoding:
Text File  |  2002-10-03  |  16.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))                                                      ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt, _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt______rrrr, _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm, _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm______rrrr, _ssss_eeee_tttt_ssss_pppp_eeee_nnnn_tttt, _eeee_nnnn_dddd_ssss_pppp_eeee_nnnn_tttt,
  10.      _ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt, _ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt______rrrr, _llll_cccc_kkkk_pppp_wwww_dddd_ffff, _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff - manipulate shadow password
  11.      file entry
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_hhhh_aaaa_dddd_oooo_wwww_...._hhhh_>>>>
  15.  
  16.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  17.  
  18.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt______rrrr _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ssss_pppp_eeee_nnnn_tttt_,,,, _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_ffff_eeee_rrrr_,,,, _iiii_nnnn_tttt _bbbb_uuuu_ffff_ssss_iiii_zzzz_eeee_))))_;;;;
  19.  
  20.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt _((((_FFFF_IIII_LLLL_EEEE _****_))))_;;;;
  21.  
  22.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt______rrrr _((((_FFFF_IIII_LLLL_EEEE _****_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ssss_pppp_eeee_nnnn_tttt_,,,, _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_ffff_eeee_rrrr_,,,, _iiii_nnnn_tttt
  23.      _bbbb_uuuu_ffff_ssss_iiii_zzzz_eeee_))))_;;;;
  24.  
  25.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_nnnn_aaaa_mmmm_eeee_))))_;;;;
  26.  
  27.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm______rrrr _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_nnnn_aaaa_mmmm_eeee_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ssss_pppp_eeee_nnnn_tttt_,,,, _cccc_hhhh_aaaa_rrrr
  28.      _****_bbbb_uuuu_ffff_ffff_eeee_rrrr_,,,, _iiii_nnnn_tttt _bbbb_uuuu_ffff_ssss_iiii_zzzz_eeee_))))_;;;;
  29.  
  30.      _iiii_nnnn_tttt _llll_cccc_kkkk_pppp_wwww_dddd_ffff _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  31.  
  32.      _iiii_nnnn_tttt _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  33.  
  34.      _vvvv_oooo_iiii_dddd _ssss_eeee_tttt_ssss_pppp_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  35.  
  36.      _vvvv_oooo_iiii_dddd _eeee_nnnn_dddd_ssss_pppp_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  37.  
  38.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt _((((_FFFF_IIII_LLLL_EEEE _****_ffff_pppp_))))_;;;;
  39.  
  40.      _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt______rrrr _((((_FFFF_IIII_LLLL_EEEE _****_ffff_pppp_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd _****_ssss_pppp_eeee_nnnn_tttt_,,,, _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_ffff_eeee_rrrr_,,,, _iiii_nnnn_tttt
  41.      _bbbb_uuuu_ffff_ssss_iiii_zzzz_eeee_))))_;;;;
  42.  
  43. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  44.      The _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt, _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm and their reentrant counterpart routines each
  45.      return a pointer to an object with the following structure containing the
  46.      broken-out fields of a line in the _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww file, or some other back-
  47.      end database.  Each line in the file contains a ``shadow password''
  48.      structure, declared in the _ssss_hhhh_aaaa_dddd_oooo_wwww_...._hhhh header file:
  49.  
  50.           _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_pppp_wwww_dddd_{{{{
  51.                _cccc_hhhh_aaaa_rrrr _****_ssss_pppp______nnnn_aaaa_mmmm_pppp_;;;;
  52.                _cccc_hhhh_aaaa_rrrr _****_ssss_pppp______pppp_wwww_dddd_pppp_;;;;
  53.                _llll_oooo_nnnn_gggg _ssss_pppp______llll_ssss_tttt_cccc_hhhh_gggg_;;;;
  54.                _llll_oooo_nnnn_gggg _ssss_pppp______mmmm_iiii_nnnn_;;;;
  55.                _llll_oooo_nnnn_gggg _ssss_pppp______mmmm_aaaa_xxxx_;;;;
  56.                _llll_oooo_nnnn_gggg _ssss_pppp______wwww_aaaa_rrrr_nnnn_;;;;
  57.                _llll_oooo_nnnn_gggg _ssss_pppp______iiii_nnnn_aaaa_cccc_tttt_;;;;
  58.                _llll_oooo_nnnn_gggg _ssss_pppp______eeee_xxxx_pppp_iiii_rrrr_eeee_;;;;
  59.                _uuuu_nnnn_ssss_iiii_gggg_nnnn_eeee_dddd _llll_oooo_nnnn_gggg  _ssss_pppp______ffff_llll_aaaa_gggg_;;;;
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))                                                      ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))
  71.  
  72.  
  73.  
  74.           _}}}}_;;;;
  75.  
  76.      The _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt routine when first called returns a pointer to the first
  77.      _ssss_pppp_wwww_dddd structure in the file; thereafter, it returns a pointer to the next
  78.      _ssss_pppp_wwww_dddd structure in the file; so successive calls can be used to search the
  79.      entire file.  The _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm routine searches from the beginning of the
  80.      file until a login name matching _n_a_m_e is found, and returns a pointer to
  81.      the particular structure in which it was found.  The _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt and
  82.      _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm routines populate the _ssss_pppp______mmmm_iiii_nnnn, _ssss_pppp______mmmm_aaaa_xxxx, _ssss_pppp______llll_ssss_tttt_cccc_hhhh_gggg, _ssss_pppp______wwww_aaaa_rrrr_nnnn,
  83.      _ssss_pppp______iiii_nnnn_aaaa_cccc_tttt, _ssss_pppp______eeee_xxxx_pppp_iiii_rrrr_eeee, or _ssss_pppp______ffff_llll_aaaa_gggg field with -1 if the corresponding field
  84.      in _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww is empty. If an end-of-file or an error is encountered on
  85.      reading, or there is a format error in the file, these functions return a
  86.      null pointer and set _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_IIII_NNNN_VVVV_AAAA_LLLL.
  87.  
  88.      _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk is the lock file.  It is used to coordinate modification
  89.      access to the password files _////_eeee_tttt_cccc_////_pppp_aaaa_ssss_ssss_wwww_dddd and _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww.  _llll_cccc_kkkk_pppp_wwww_dddd_ffff and
  90.      _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff are routines that are used to gain modification access to the
  91.      password files, through the lock file.  A process first uses _llll_cccc_kkkk_pppp_wwww_dddd_ffff to
  92.      lock the lock file, thereby gaining exclusive rights to modify the
  93.      _////_eeee_tttt_cccc_////_pppp_aaaa_ssss_ssss_wwww_dddd or _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww password file.  Upon completing modifications,
  94.      a process should release the lock on the lock file via _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff.  This
  95.      mechanism prevents simultaneous modification of the password files.
  96.  
  97.      _llll_cccc_kkkk_pppp_wwww_dddd_ffff attempts to lock the file _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk within 15 seconds.  If
  98.      unsuccessful, e.g., _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk is already locked, it returns -1.  If
  99.      successful, a return code other than -1 is returned.
  100.  
  101.      _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff attempts to unlock the file _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk.  If unsuccessful,
  102.      e.g., _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk is already unlocked, it returns -1.  If successful,
  103.      it returns 0.
  104.  
  105.      A call to the _ssss_eeee_tttt_ssss_pppp_eeee_nnnn_tttt routine has the effect of rewinding the shadow
  106.      password file to allow repeated searches.  The _eeee_nnnn_dddd_ssss_pppp_eeee_nnnn_tttt routine may be
  107.      called to close the shadow password file when processing is complete.
  108.  
  109.      The _ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt routine returns a pointer to the next _ssss_pppp_wwww_dddd structure in the
  110.      stream _f_p, which matches the format of _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww.
  111.  
  112.      Many SVR4 derived programs use these routines exclusively to get password
  113.      and aging information.  These programs assume that all systems have a
  114.      _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww file.  Historically, IRIX has not had a _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww file so
  115.      in order to permit these standard SVR4 programs to work properly,
  116.      _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm, in the absence of a shadow file, will get as much information
  117.      as possible from _////_eeee_tttt_cccc_////_pppp_aaaa_ssss_ssss_wwww_dddd.  _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt does not have this compatibility
  118.      feature, and will return NULL if the system has no _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww file.
  119.  
  120.      The routines getspent, fgetspent and getspnam return results in a
  121.      statically allocated memory location which is overwritten on each call.
  122.      Reentrant versions of each of these routines getspent_r, fgetspent_r and
  123.      getspnam_r which will parse the results into supplied memory.  Each takes
  124.      three extra parameters, a pointer to a shadow password structure, a
  125.      pointer to a character buffer, and a length for the buffer.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))                                                      ggggeeeettttssssppppeeeennnntttt((((3333CCCC))))
  137.  
  138.  
  139.  
  140. NNNNOOOOTTTTEEEE
  141.      The Mips ABI specifies nothing but local files so applications which wish
  142.      to use anything else must compile with libc prior to libnsl in the
  143.      library list.
  144.  
  145.      When nsd is running changes to the local shadow file may not be noticed
  146.      by getspent() until the enumeration cache file has timed out.
  147.  
  148. FFFFIIIILLLLEEEESSSS
  149.      _////_eeee_tttt_cccc_////_ssss_hhhh_aaaa_dddd_oooo_wwww
  150.      _////_eeee_tttt_cccc_////_pppp_aaaa_ssss_ssss_wwww_dddd
  151.      _////_eeee_tttt_cccc_////_...._pppp_wwww_dddd_...._llll_oooo_cccc_kkkk
  152.      _////_eeee_tttt_cccc_////_nnnn_ssss_ssss_wwww_iiii_tttt_cccc_hhhh_...._cccc_oooo_nnnn_ffff
  153.      _////_vvvv_aaaa_rrrr_////_nnnn_ssss_////_cccc_aaaa_cccc_hhhh_eeee_////_ssss_hhhh_aaaa_dddd_oooo_wwww_...._bbbb_yyyy_nnnn_aaaa_mmmm_eeee_...._mmmm
  154.  
  155. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  156.      _nnnn_ssss_dddd(1M), _gggg_eeee_tttt_pppp_wwww_eeee_nnnn_tttt(3C), _pppp_uuuu_tttt_pppp_wwww_eeee_nnnn_tttt(3C), _pppp_uuuu_tttt_ssss_pppp_eeee_nnnn_tttt(3C).
  157.  
  158. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  159.      _gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt, _gggg_eeee_tttt_ssss_pppp_nnnn_aaaa_mmmm, and _ffff_gggg_eeee_tttt_ssss_pppp_eeee_nnnn_tttt return a null pointer on _EEEE_OOOO_FFFF or error.
  160.  
  161.      _llll_cccc_kkkk_pppp_wwww_dddd_ffff and _uuuu_llll_cccc_kkkk_pppp_wwww_dddd_ffff return -1 on error.
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.